| Server IP : 121.121.20.254 / Your IP : 216.73.216.202 Web Server : Microsoft-IIS/10.0 System : Windows NT WEB-SERVER 10.0 build 20348 (Windows Server 2022) AMD64 User : IUSR ( 0) PHP Version : 8.3.28 Disable Function : NONE MySQL : ON | cURL : ON | WGET : OFF | Perl : OFF | Python : OFF | Sudo : OFF | Pkexec : OFF Directory : C:/Python315/Doc/html/c-api/ |
Upload File : |
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta property="og:title" content="Interpreter initialization and finalization" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/c-api/interp-lifecycle.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="See Python Initialization Configuration for details on how to configure the interpreter prior to initialization. Before Python initialization: In an application embedding Python, the Py_Initialize(..." />
<meta property="og:image" content="_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="See Python Initialization Configuration for details on how to configure the interpreter prior to initialization. Before Python initialization: In an application embedding Python, the Py_Initialize(..." />
<meta name="theme-color" content="#3776ab">
<meta property="og:image:width" content="200">
<meta property="og:image:height" content="200">
<title>Interpreter initialization and finalization — Python 3.15.0rc1 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=4365c8fe" />
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=0fc419ee" />
<script src="../_static/documentation_options.js?v=791e38b1"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.15.0rc1 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Thread states and the global interpreter lock" href="threads.html" />
<link rel="prev" title="DateTime Objects" href="datetime.html" />
<link rel="canonical" href="https://docs.python.org/3/c-api/interp-lifecycle.html">
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
<link rel="shortcut icon" type="image/png" href="../_static/py.svg">
<script type="text/javascript" src="../_static/copybutton.js"></script>
<script type="text/javascript" src="../_static/menu.js"></script>
<script type="text/javascript" src="../_static/search-focus.js"></script>
<script type="text/javascript" src="../_static/themetoggle.js"></script>
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
<meta name="readthedocs-addons-api-version" content="1">
</head>
<body>
<div class="mobile-nav">
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">
<nav class="nav-content" role="navigation">
<label for="menuToggler" class="toggler__label">
<span></span>
</label>
<span class="nav-items-wrapper">
<a href="https://www.python.org/" class="nav-logo">
<img src="../_static/py.svg" alt="Python logo">
</a>
<span class="version_switcher_placeholder"></span>
<form role="search" class="search" action="../search.html" method="get">
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
</svg>
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q">
<input type="submit" value="Go">
</form>
</span>
</nav>
<div class="menu-wrapper">
<nav class="menu" role="navigation" aria-label="main navigation">
<div class="language_switcher_placeholder"></div>
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label>
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Interpreter initialization and finalization</a><ul>
<li><a class="reference internal" href="#before-python-initialization">Before Python initialization</a></li>
<li><a class="reference internal" href="#global-configuration-variables">Global configuration variables</a></li>
<li><a class="reference internal" href="#initializing-and-finalizing-the-interpreter">Initializing and finalizing the interpreter</a></li>
<li><a class="reference internal" href="#cautions-regarding-interpreter-finalization">Cautions regarding interpreter finalization</a></li>
<li><a class="reference internal" href="#interpreter-views">Interpreter views</a></li>
<li><a class="reference internal" href="#process-wide-parameters">Process-wide parameters</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="datetime.html"
title="previous chapter">DateTime Objects</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="threads.html"
title="next chapter">Thread states and the global interpreter lock</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "c-api/interp-lifecycle.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/c-api/interp-lifecycle.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</nav>
</div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="threads.html" title="Thread states and the global interpreter lock"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="datetime.html" title="DateTime Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0rc1 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API reference manual</a> »</li>
<li class="nav-item nav-item-this"><a href="">Interpreter initialization and finalization</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="interpreter-initialization-and-finalization">
<span id="initialization"></span><h1>Interpreter initialization and finalization<a class="headerlink" href="#interpreter-initialization-and-finalization" title="Link to this heading">¶</a></h1>
<p>See <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a> for details
on how to configure the interpreter prior to initialization.</p>
<section id="before-python-initialization">
<span id="pre-init-safe"></span><h2>Before Python initialization<a class="headerlink" href="#before-python-initialization" title="Link to this heading">¶</a></h2>
<p>In an application embedding Python, the <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> function must
be called before using any other Python/C API functions; with the exception of
a few functions and the <a class="reference internal" href="#global-conf-vars"><span class="std std-ref">global configuration variables</span></a>.</p>
<p>The following functions can be safely called before Python is initialized:</p>
<ul class="simple">
<li><p>Functions that initialize the interpreter:</p>
<ul>
<li><p><a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_InitializeEx" title="Py_InitializeEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_InitializeEx()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_InitializeFromConfig" title="Py_InitializeFromConfig"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_InitializeFromConfig()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_BytesMain" title="Py_BytesMain"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BytesMain()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_Main" title="Py_Main"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Main()</span></code></a></p></li>
<li><p>the runtime pre-initialization functions covered in <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a></p></li>
</ul>
</li>
<li><p>Configuration functions:</p>
<ul>
<li><p><a class="reference internal" href="import.html#c.PyImport_AppendInittab" title="PyImport_AppendInittab"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_AppendInittab()</span></code></a></p></li>
<li><p><a class="reference internal" href="import.html#c.PyImport_ExtendInittab" title="PyImport_ExtendInittab"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ExtendInittab()</span></code></a></p></li>
<li><p><code class="xref c c-func docutils literal notranslate"><span class="pre">PyInitFrozenExtensions()</span></code></p></li>
<li><p><a class="reference internal" href="memory.html#c.PyMem_SetAllocator" title="PyMem_SetAllocator"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_SetAllocator()</span></code></a></p></li>
<li><p><a class="reference internal" href="memory.html#c.PyMem_SetupDebugHooks" title="PyMem_SetupDebugHooks"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_SetupDebugHooks()</span></code></a></p></li>
<li><p><a class="reference internal" href="memory.html#c.PyObject_SetArenaAllocator" title="PyObject_SetArenaAllocator"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_SetArenaAllocator()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_SetProgramName" title="Py_SetProgramName"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_SetProgramName()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_SetPythonHome" title="Py_SetPythonHome"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_SetPythonHome()</span></code></a></p></li>
<li><p>the configuration functions covered in <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a></p></li>
</ul>
</li>
<li><p>Informative functions:</p>
<ul>
<li><p><a class="reference internal" href="#c.Py_IsInitialized" title="Py_IsInitialized"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_IsInitialized()</span></code></a></p></li>
<li><p><a class="reference internal" href="memory.html#c.PyMem_GetAllocator" title="PyMem_GetAllocator"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_GetAllocator()</span></code></a></p></li>
<li><p><a class="reference internal" href="memory.html#c.PyObject_GetArenaAllocator" title="PyObject_GetArenaAllocator"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetArenaAllocator()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_GetBuildInfo" title="Py_GetBuildInfo"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_GetBuildInfo()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_GetCompiler" title="Py_GetCompiler"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_GetCompiler()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_GetCopyright" title="Py_GetCopyright"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_GetCopyright()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_GetPlatform" title="Py_GetPlatform"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_GetPlatform()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_GetVersion" title="Py_GetVersion"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_GetVersion()</span></code></a></p></li>
<li><p><a class="reference internal" href="#c.Py_IsInitialized" title="Py_IsInitialized"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_IsInitialized()</span></code></a></p></li>
</ul>
</li>
<li><p>Utilities:</p>
<ul>
<li><p><a class="reference internal" href="sys.html#c.Py_DecodeLocale" title="Py_DecodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DecodeLocale()</span></code></a></p></li>
<li><p>the status reporting and utility functions covered in <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a></p></li>
</ul>
</li>
<li><p>Memory allocators:</p>
<ul>
<li><p><a class="reference internal" href="memory.html#c.PyMem_RawMalloc" title="PyMem_RawMalloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_RawMalloc()</span></code></a></p></li>
<li><p><a class="reference internal" href="memory.html#c.PyMem_RawRealloc" title="PyMem_RawRealloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_RawRealloc()</span></code></a></p></li>
<li><p><a class="reference internal" href="memory.html#c.PyMem_RawCalloc" title="PyMem_RawCalloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_RawCalloc()</span></code></a></p></li>
<li><p><a class="reference internal" href="memory.html#c.PyMem_RawFree" title="PyMem_RawFree"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_RawFree()</span></code></a></p></li>
</ul>
</li>
<li><p>Synchronization:</p>
<ul>
<li><p><a class="reference internal" href="synchronization.html#c.PyMutex_Lock" title="PyMutex_Lock"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMutex_Lock()</span></code></a></p></li>
<li><p><a class="reference internal" href="synchronization.html#c.PyMutex_Unlock" title="PyMutex_Unlock"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMutex_Unlock()</span></code></a></p></li>
</ul>
</li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Despite their apparent similarity to some of the functions listed above,
the following functions <strong>should not be called</strong> before the interpreter has
been initialized: <a class="reference internal" href="sys.html#c.Py_EncodeLocale" title="Py_EncodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_EncodeLocale()</span></code></a>, <a class="reference internal" href="threads.html#c.PyEval_InitThreads" title="PyEval_InitThreads"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_InitThreads()</span></code></a>, and
<a class="reference internal" href="#c.Py_RunMain" title="Py_RunMain"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_RunMain()</span></code></a>.</p>
</div>
</section>
<section id="global-configuration-variables">
<span id="global-conf-vars"></span><h2>Global configuration variables<a class="headerlink" href="#global-configuration-variables" title="Link to this heading">¶</a></h2>
<p>Python has variables for the global configuration to control different features
and options. By default, these flags are controlled by <a class="reference internal" href="../using/cmdline.html#using-on-interface-options"><span class="std std-ref">command line
options</span></a>.</p>
<p>When a flag is set by an option, the value of the flag is the number of times
that the option was set. For example, <code class="docutils literal notranslate"><span class="pre">-b</span></code> sets <a class="reference internal" href="#c.Py_BytesWarningFlag" title="Py_BytesWarningFlag"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_BytesWarningFlag</span></code></a>
to 1 and <code class="docutils literal notranslate"><span class="pre">-bb</span></code> sets <code class="xref c c-data docutils literal notranslate"><span class="pre">Py_BytesWarningFlag</span></code> to 2.</p>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_BytesWarningFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_BytesWarningFlag</span></span></span><a class="headerlink" href="#c.Py_BytesWarningFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.bytes_warning" title="PyConfig.bytes_warning"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.bytes_warning</span></code></a> should be used instead, see <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python
Initialization Configuration</span></a>.</p>
<p>Issue a warning when comparing <a class="reference internal" href="../library/stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> or <a class="reference internal" href="../library/stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a> with
<a class="reference internal" href="../library/stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code> with <a class="reference internal" href="../library/functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate"><span class="pre">int</span></code></a>. Issue an error if greater
or equal to <code class="docutils literal notranslate"><span class="pre">2</span></code>.</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-b"><code class="xref std std-option docutils literal notranslate"><span class="pre">-b</span></code></a> option.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_DebugFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_DebugFlag</span></span></span><a class="headerlink" href="#c.Py_DebugFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.parser_debug" title="PyConfig.parser_debug"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.parser_debug</span></code></a> should be used instead, see <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python
Initialization Configuration</span></a>.</p>
<p>Turn on parser debugging output (for expert only, depending on compilation
options).</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-d"><code class="xref std std-option docutils literal notranslate"><span class="pre">-d</span></code></a> option and the <span class="target" id="index-0"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONDEBUG"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONDEBUG</span></code></a> environment
variable.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_DontWriteBytecodeFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_DontWriteBytecodeFlag</span></span></span><a class="headerlink" href="#c.Py_DontWriteBytecodeFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.write_bytecode" title="PyConfig.write_bytecode"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.write_bytecode</span></code></a> should be used instead, see <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python
Initialization Configuration</span></a>.</p>
<p>If set to non-zero, Python won’t try to write <code class="docutils literal notranslate"><span class="pre">.pyc</span></code> files on the
import of source modules.</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-B"><code class="xref std std-option docutils literal notranslate"><span class="pre">-B</span></code></a> option and the <span class="target" id="index-1"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONDONTWRITEBYTECODE"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONDONTWRITEBYTECODE</span></code></a>
environment variable.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_FrozenFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_FrozenFlag</span></span></span><a class="headerlink" href="#c.Py_FrozenFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.pathconfig_warnings" title="PyConfig.pathconfig_warnings"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.pathconfig_warnings</span></code></a> should be used instead, see
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>Private flag used by <code class="docutils literal notranslate"><span class="pre">_freeze_module</span></code> and <code class="docutils literal notranslate"><span class="pre">frozenmain</span></code> programs.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_HashRandomizationFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_HashRandomizationFlag</span></span></span><a class="headerlink" href="#c.Py_HashRandomizationFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.hash_seed" title="PyConfig.hash_seed"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.hash_seed</span></code></a> and <a class="reference internal" href="init_config.html#c.PyConfig.use_hash_seed" title="PyConfig.use_hash_seed"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.use_hash_seed</span></code></a> should
be used instead, see <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>Set to <code class="docutils literal notranslate"><span class="pre">1</span></code> if the <span class="target" id="index-2"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHASHSEED"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHASHSEED</span></code></a> environment variable is set to
a non-empty string.</p>
<p>If the flag is non-zero, read the <span class="target" id="index-3"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHASHSEED"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHASHSEED</span></code></a> environment
variable to initialize the secret hash seed.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_IgnoreEnvironmentFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_IgnoreEnvironmentFlag</span></span></span><a class="headerlink" href="#c.Py_IgnoreEnvironmentFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.use_environment" title="PyConfig.use_environment"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.use_environment</span></code></a> should be used instead, see
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>Ignore all <code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHON*</span></code> environment variables, e.g.
<span class="target" id="index-4"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code></a> and <span class="target" id="index-5"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a>, that might be set.</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-E"><code class="xref std std-option docutils literal notranslate"><span class="pre">-E</span></code></a> and <a class="reference internal" href="../using/cmdline.html#cmdoption-I"><code class="xref std std-option docutils literal notranslate"><span class="pre">-I</span></code></a> options.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_InspectFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_InspectFlag</span></span></span><a class="headerlink" href="#c.Py_InspectFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.inspect" title="PyConfig.inspect"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.inspect</span></code></a> should be used instead, see
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>When a script is passed as first argument or the <a class="reference internal" href="../using/cmdline.html#cmdoption-c"><code class="xref std std-option docutils literal notranslate"><span class="pre">-c</span></code></a> option is used,
enter interactive mode after executing the script or the command, even when
<a class="reference internal" href="../library/sys.html#sys.stdin" title="sys.stdin"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdin</span></code></a> does not appear to be a terminal.</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-i"><code class="xref std std-option docutils literal notranslate"><span class="pre">-i</span></code></a> option and the <span class="target" id="index-6"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONINSPECT"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONINSPECT</span></code></a> environment
variable.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_InteractiveFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_InteractiveFlag</span></span></span><a class="headerlink" href="#c.Py_InteractiveFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.interactive" title="PyConfig.interactive"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.interactive</span></code></a> should be used instead, see
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-i"><code class="xref std std-option docutils literal notranslate"><span class="pre">-i</span></code></a> option.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_IsolatedFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_IsolatedFlag</span></span></span><a class="headerlink" href="#c.Py_IsolatedFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.isolated" title="PyConfig.isolated"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.isolated</span></code></a> should be used instead, see
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>Run Python in isolated mode. In isolated mode <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> contains
neither the script’s directory nor the user’s site-packages directory.</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-I"><code class="xref std std-option docutils literal notranslate"><span class="pre">-I</span></code></a> option.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.4.</span></p>
</div>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_LegacyWindowsFSEncodingFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_LegacyWindowsFSEncodingFlag</span></span></span><a class="headerlink" href="#c.Py_LegacyWindowsFSEncodingFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyPreConfig.legacy_windows_fs_encoding" title="PyPreConfig.legacy_windows_fs_encoding"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyPreConfig.legacy_windows_fs_encoding</span></code></a> should be used instead, see
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>If the flag is non-zero, use the <code class="docutils literal notranslate"><span class="pre">mbcs</span></code> encoding with <code class="docutils literal notranslate"><span class="pre">replace</span></code> error
handler, instead of the UTF-8 encoding with <code class="docutils literal notranslate"><span class="pre">surrogatepass</span></code> error handler,
for the <a class="reference internal" href="../glossary.html#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a>.</p>
<p>Set to <code class="docutils literal notranslate"><span class="pre">1</span></code> if the <span class="target" id="index-7"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONLEGACYWINDOWSFSENCODING"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONLEGACYWINDOWSFSENCODING</span></code></a> environment
variable is set to a non-empty string.</p>
<p>See <span class="target" id="index-8"></span><a class="pep reference external" href="https://peps.python.org/pep-0529/"><strong>PEP 529</strong></a> for more details.</p>
<div class="availability docutils container">
<p><a class="reference internal" href="../library/intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p>
</div>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_LegacyWindowsStdioFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_LegacyWindowsStdioFlag</span></span></span><a class="headerlink" href="#c.Py_LegacyWindowsStdioFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.legacy_windows_stdio" title="PyConfig.legacy_windows_stdio"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.legacy_windows_stdio</span></code></a> should be used instead, see
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>If the flag is non-zero, use <a class="reference internal" href="../library/io.html#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.FileIO</span></code></a> instead of
<code class="xref py py-class docutils literal notranslate"><span class="pre">io._WindowsConsoleIO</span></code> for <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a> standard streams.</p>
<p>Set to <code class="docutils literal notranslate"><span class="pre">1</span></code> if the <span class="target" id="index-9"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONLEGACYWINDOWSSTDIO"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONLEGACYWINDOWSSTDIO</span></code></a> environment
variable is set to a non-empty string.</p>
<p>See <span class="target" id="index-10"></span><a class="pep reference external" href="https://peps.python.org/pep-0528/"><strong>PEP 528</strong></a> for more details.</p>
<div class="availability docutils container">
<p><a class="reference internal" href="../library/intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p>
</div>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_NoSiteFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_NoSiteFlag</span></span></span><a class="headerlink" href="#c.Py_NoSiteFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.site_import" title="PyConfig.site_import"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.site_import</span></code></a> should be used instead, see
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>Disable the import of the module <a class="reference internal" href="../library/site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a> and the site-dependent
manipulations of <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> that it entails. Also disable these
manipulations if <code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code> is explicitly imported later (call
<a class="reference internal" href="../library/site.html#site.main" title="site.main"><code class="xref py py-func docutils literal notranslate"><span class="pre">site.main()</span></code></a> if you want them to be triggered).</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-S"><code class="xref std std-option docutils literal notranslate"><span class="pre">-S</span></code></a> option.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_NoUserSiteDirectory">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_NoUserSiteDirectory</span></span></span><a class="headerlink" href="#c.Py_NoUserSiteDirectory" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.user_site_directory" title="PyConfig.user_site_directory"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.user_site_directory</span></code></a> should be used instead, see
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>Don’t add the <a class="reference internal" href="../library/site.html#site.USER_SITE" title="site.USER_SITE"><code class="xref py py-data docutils literal notranslate"><span class="pre">user</span> <span class="pre">site-packages</span> <span class="pre">directory</span></code></a> to
<a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>.</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-s"><code class="xref std std-option docutils literal notranslate"><span class="pre">-s</span></code></a> and <a class="reference internal" href="../using/cmdline.html#cmdoption-I"><code class="xref std std-option docutils literal notranslate"><span class="pre">-I</span></code></a> options, and the
<span class="target" id="index-11"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONNOUSERSITE"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONNOUSERSITE</span></code></a> environment variable.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_OptimizeFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_OptimizeFlag</span></span></span><a class="headerlink" href="#c.Py_OptimizeFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.optimization_level" title="PyConfig.optimization_level"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.optimization_level</span></code></a> should be used instead, see
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-O"><code class="xref std std-option docutils literal notranslate"><span class="pre">-O</span></code></a> option and the <span class="target" id="index-12"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONOPTIMIZE"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONOPTIMIZE</span></code></a> environment
variable.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_QuietFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_QuietFlag</span></span></span><a class="headerlink" href="#c.Py_QuietFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.quiet" title="PyConfig.quiet"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.quiet</span></code></a> should be used instead, see <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python
Initialization Configuration</span></a>.</p>
<p>Don’t display the copyright and version messages even in interactive mode.</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-q"><code class="xref std std-option docutils literal notranslate"><span class="pre">-q</span></code></a> option.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.2.</span></p>
</div>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_UnbufferedStdioFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_UnbufferedStdioFlag</span></span></span><a class="headerlink" href="#c.Py_UnbufferedStdioFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.buffered_stdio" title="PyConfig.buffered_stdio"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.buffered_stdio</span></code></a> should be used instead, see <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python
Initialization Configuration</span></a>.</p>
<p>Force the stdout and stderr streams to be unbuffered.</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-u"><code class="xref std std-option docutils literal notranslate"><span class="pre">-u</span></code></a> option and the <span class="target" id="index-13"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONUNBUFFERED"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONUNBUFFERED</span></code></a>
environment variable.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c var">
<dt class="sig sig-object c" id="c.Py_VerboseFlag">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_VerboseFlag</span></span></span><a class="headerlink" href="#c.Py_VerboseFlag" title="Link to this definition">¶</a><br /></dt>
<dd><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.verbose" title="PyConfig.verbose"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.verbose</span></code></a> should be used instead, see <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python
Initialization Configuration</span></a>.</p>
<p>Print a message each time a module is initialized, showing the place
(filename or built-in module) from which it is loaded. If greater or equal
to <code class="docutils literal notranslate"><span class="pre">2</span></code>, print a message for each file that is checked for when
searching for a module. Also provides information on module cleanup at exit.</p>
<p>Set by the <a class="reference internal" href="../using/cmdline.html#cmdoption-v"><code class="xref std std-option docutils literal notranslate"><span class="pre">-v</span></code></a> option and the <span class="target" id="index-14"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONVERBOSE"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONVERBOSE</span></code></a> environment
variable.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.12, removed in version 3.15.</span></p>
</div>
</dd></dl>
</section>
<section id="initializing-and-finalizing-the-interpreter">
<h2>Initializing and finalizing the interpreter<a class="headerlink" href="#initializing-and-finalizing-the-interpreter" title="Link to this heading">¶</a></h2>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_Initialize">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_Initialize</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_Initialize" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-15">Initialize the Python interpreter. In an application embedding Python,
this should be called before using any other Python/C API functions; see
<a class="reference internal" href="#pre-init-safe"><span class="std std-ref">Before Python Initialization</span></a> for the few exceptions.</p>
<p>This initializes the table of loaded modules (<code class="docutils literal notranslate"><span class="pre">sys.modules</span></code>), and creates
the fundamental modules <a class="reference internal" href="../library/builtins.html#module-builtins" title="builtins: The module that provides the built-in namespace."><code class="xref py py-mod docutils literal notranslate"><span class="pre">builtins</span></code></a>, <a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where top-level code is run. Covers command-line interfaces, import-time behavior, and ``__name__ == '__main__'``."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a> and <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a>.
It also initializes the module search path (<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>). It does not set
<code class="docutils literal notranslate"><span class="pre">sys.argv</span></code>; use the <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>
API for that. This is a no-op when called for a second time (without calling
<a class="reference internal" href="#c.Py_FinalizeEx" title="Py_FinalizeEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_FinalizeEx()</span></code></a> first). There is no return value; it is a fatal
error if the initialization fails.</p>
<p>Use <a class="reference internal" href="#c.Py_InitializeFromConfig" title="Py_InitializeFromConfig"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_InitializeFromConfig()</span></code></a> to customize the
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>On Windows, changes the console mode from <code class="docutils literal notranslate"><span class="pre">O_TEXT</span></code> to <code class="docutils literal notranslate"><span class="pre">O_BINARY</span></code>,
which will also affect non-Python uses of the console using the C Runtime.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_InitializeEx">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_InitializeEx</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">initsigs</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_InitializeEx" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This function works like <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> if <em>initsigs</em> is <code class="docutils literal notranslate"><span class="pre">1</span></code>. If
<em>initsigs</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, it skips initialization registration of signal handlers,
which may be useful when CPython is embedded as part of a larger application.</p>
<p>Use <a class="reference internal" href="#c.Py_InitializeFromConfig" title="Py_InitializeFromConfig"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_InitializeFromConfig()</span></code></a> to customize the
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_InitializeFromConfig">
<a class="reference internal" href="init_config.html#c.PyStatus" title="PyStatus"><span class="n"><span class="pre">PyStatus</span></span></a><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_InitializeFromConfig</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><a class="reference internal" href="init_config.html#c.PyConfig" title="PyConfig"><span class="n"><span class="pre">PyConfig</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">config</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_InitializeFromConfig" title="Link to this definition">¶</a><br /></dt>
<dd><p>Initialize Python from <em>config</em> configuration, as described in
<a class="reference internal" href="init_config.html#init-from-config"><span class="std std-ref">Initialization with PyConfig</span></a>.</p>
<p>See the <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a> section for details on pre-initializing the
interpreter, populating the runtime configuration structure, and querying
the returned status structure.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_IsInitialized">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_IsInitialized</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_IsInitialized" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return true (nonzero) when the Python interpreter has been initialized, false
(zero) if not. After <a class="reference internal" href="#c.Py_FinalizeEx" title="Py_FinalizeEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_FinalizeEx()</span></code></a> is called, this returns false until
<a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> is called again.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.15: </span>This function no longer returns true until initialization has fully
completed, including import of the <a class="reference internal" href="../library/site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal notranslate"><span class="pre">site</span></code></a> module. Previously it
could return true while <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> was still running.</p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_IsFinalizing">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_IsFinalizing</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_IsFinalizing" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.13.</em><p>Return true (non-zero) if the main Python interpreter is
<a class="reference internal" href="../glossary.html#term-interpreter-shutdown"><span class="xref std std-term">shutting down</span></a>. Return false (zero) otherwise.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.13.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_FinalizeEx">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_FinalizeEx</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_FinalizeEx" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.6.</em><p>Undo all initializations made by <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> and subsequent use of
Python/C API functions, and destroy all sub-interpreters (see
<a class="reference internal" href="subinterpreters.html#c.Py_NewInterpreter" title="Py_NewInterpreter"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_NewInterpreter()</span></code></a> below) that were created and not yet destroyed since
the last call to <code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code>. This is a no-op when called for a second
time (without calling <code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code> again first).</p>
<p>Since this is the reverse of <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>, it should be called
in the same thread with the same interpreter active. That means
the main thread and the main interpreter.
This should never be called while <a class="reference internal" href="#c.Py_RunMain" title="Py_RunMain"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_RunMain()</span></code></a> is running.</p>
<p>Normally the return value is <code class="docutils literal notranslate"><span class="pre">0</span></code>.
If there were errors during finalization (flushing buffered data),
<code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned.</p>
<p>Note that Python will do a best effort at freeing all memory allocated by the Python
interpreter. Therefore, any C-Extension should make sure to correctly clean up all
of the previously allocated PyObjects before using them in subsequent calls to
<a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>. Otherwise it could introduce vulnerabilities and incorrect
behavior.</p>
<p>This function is provided for a number of reasons. An embedding application
might want to restart Python without having to restart the application itself.
An application that has loaded the Python interpreter from a dynamically
loadable library (or DLL) might want to free all memory allocated by Python
before unloading the DLL. During a hunt for memory leaks in an application a
developer might want to free all memory allocated by Python before exiting from
the application.</p>
<p><strong>Bugs and caveats:</strong> The destruction of modules and objects in modules is done
in random order; this may cause destructors (<a class="reference internal" href="../reference/datamodel.html#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> methods) to fail
when they depend on other objects (even functions) or modules. Dynamically
loaded extension modules loaded by Python are not unloaded. Small amounts of
memory allocated by the Python interpreter may not be freed (if you find a leak,
please report it). Memory tied up in circular references between objects is not
freed. Interned strings will all be deallocated regardless of their reference count.
Some memory allocated by extension modules may not be freed. Some extensions may not
work properly if their initialization routine is called more than once; this can
happen if an application calls <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> and <a class="reference internal" href="#c.Py_FinalizeEx" title="Py_FinalizeEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_FinalizeEx()</span></code></a>
more than once. <code class="xref c c-func docutils literal notranslate"><span class="pre">Py_FinalizeEx()</span></code> must not be called recursively from
within itself. Therefore, it must not be called by any code that may be run
as part of the interpreter shutdown process, such as <a class="reference internal" href="../library/atexit.html#module-atexit" title="atexit: Register and execute cleanup functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">atexit</span></code></a>
handlers, object finalizers, or any code that may be run while flushing the
stdout and stderr files.</p>
<p class="audit-hook">Raises an <a class="reference internal" href="../library/sys.html#auditing"><span class="std std-ref">auditing event</span></a> <code class="docutils literal notranslate"><span class="pre">cpython._PySys_ClearAuditHooks</span></code> with no arguments.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.6.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_Finalize">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_Finalize</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_Finalize" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This is a backwards-compatible version of <a class="reference internal" href="#c.Py_FinalizeEx" title="Py_FinalizeEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_FinalizeEx()</span></code></a> that
disregards the return value.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_BytesMain">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_BytesMain</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">argc</span></span>, <span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">argv</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_BytesMain" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.8.</em><p>Similar to <a class="reference internal" href="#c.Py_Main" title="Py_Main"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Main()</span></code></a> but <em>argv</em> is an array of bytes strings,
allowing the calling application to delegate the text decoding step to
the CPython runtime.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.8.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_Main">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_Main</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">argc</span></span>, <span class="n"><span class="pre">wchar_t</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">argv</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_Main" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>The main program for the standard interpreter, encapsulating a full
initialization/finalization cycle, as well as additional
behaviour to implement reading configurations settings from the environment
and command line, and then executing <code class="docutils literal notranslate"><span class="pre">__main__</span></code> in accordance with
<a class="reference internal" href="../using/cmdline.html#using-on-cmdline"><span class="std std-ref">Command line</span></a>.</p>
<p>This is made available for programs which wish to support the full CPython
command line interface, rather than just embedding a Python runtime in a
larger application.</p>
<p>The <em>argc</em> and <em>argv</em> parameters are similar to those which are passed to a
C program’s <code class="xref c c-func docutils literal notranslate"><span class="pre">main()</span></code> function, except that the <em>argv</em> entries are first
converted to <code class="docutils literal notranslate"><span class="pre">wchar_t</span></code> using <a class="reference internal" href="sys.html#c.Py_DecodeLocale" title="Py_DecodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DecodeLocale()</span></code></a>. It is also
important to note that the argument list entries may be modified to point to
strings other than those passed in (however, the contents of the strings
pointed to by the argument list are not modified).</p>
<p>The return value is <code class="docutils literal notranslate"><span class="pre">2</span></code> if the argument list does not represent a valid
Python command line, and otherwise the same as <a class="reference internal" href="#c.Py_RunMain" title="Py_RunMain"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_RunMain()</span></code></a>.</p>
<p>In terms of the CPython runtime configuration APIs documented in the
<a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">runtime configuration</span></a> section (and without accounting
for error handling), <code class="docutils literal notranslate"><span class="pre">Py_Main</span></code> is approximately equivalent to:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyConfig</span><span class="w"> </span><span class="n">config</span><span class="p">;</span>
<span class="n">PyConfig_InitPythonConfig</span><span class="p">(</span><span class="o">&</span><span class="n">config</span><span class="p">);</span>
<span class="n">PyConfig_SetArgv</span><span class="p">(</span><span class="o">&</span><span class="n">config</span><span class="p">,</span><span class="w"> </span><span class="n">argc</span><span class="p">,</span><span class="w"> </span><span class="n">argv</span><span class="p">);</span>
<span class="n">Py_InitializeFromConfig</span><span class="p">(</span><span class="o">&</span><span class="n">config</span><span class="p">);</span>
<span class="n">PyConfig_Clear</span><span class="p">(</span><span class="o">&</span><span class="n">config</span><span class="p">);</span>
<span class="n">Py_RunMain</span><span class="p">();</span>
</pre></div>
</div>
<p>In normal usage, an embedding application will call this function
<em>instead</em> of calling <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>, <a class="reference internal" href="#c.Py_InitializeEx" title="Py_InitializeEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_InitializeEx()</span></code></a> or
<a class="reference internal" href="#c.Py_InitializeFromConfig" title="Py_InitializeFromConfig"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_InitializeFromConfig()</span></code></a> directly, and all settings will be applied
as described elsewhere in this documentation. If this function is instead
called <em>after</em> a preceding runtime initialization API call, then exactly
which environmental and command line configuration settings will be updated
is version dependent (as it depends on which settings correctly support
being modified after they have already been set once when the runtime was
first initialized).</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_RunMain">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_RunMain</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_RunMain" title="Link to this definition">¶</a><br /></dt>
<dd><p>Executes the main module in a fully configured CPython runtime.</p>
<p>Executes the command (<a class="reference internal" href="init_config.html#c.PyConfig.run_command" title="PyConfig.run_command"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.run_command</span></code></a>), the script
(<a class="reference internal" href="init_config.html#c.PyConfig.run_filename" title="PyConfig.run_filename"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.run_filename</span></code></a>) or the module
(<a class="reference internal" href="init_config.html#c.PyConfig.run_module" title="PyConfig.run_module"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.run_module</span></code></a>) specified on the command line or in the
configuration. If none of these values are set, runs the interactive Python
prompt (REPL) using the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module’s global namespace.</p>
<p>If <a class="reference internal" href="init_config.html#c.PyConfig.inspect" title="PyConfig.inspect"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.inspect</span></code></a> is not set (the default), the return value
will be <code class="docutils literal notranslate"><span class="pre">0</span></code> if the interpreter exits normally (that is, without raising
an exception), the exit status of an unhandled <a class="reference internal" href="../library/exceptions.html#SystemExit" title="SystemExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code></a>, or <code class="docutils literal notranslate"><span class="pre">1</span></code>
for any other unhandled exception.</p>
<p>If <a class="reference internal" href="init_config.html#c.PyConfig.inspect" title="PyConfig.inspect"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.inspect</span></code></a> is set (such as when the <a class="reference internal" href="../using/cmdline.html#cmdoption-i"><code class="xref std std-option docutils literal notranslate"><span class="pre">-i</span></code></a> option
is used), rather than returning when the interpreter exits, execution will
instead resume in an interactive Python prompt (REPL) using the <code class="docutils literal notranslate"><span class="pre">__main__</span></code>
module’s global namespace. If the interpreter exited with an exception, it
is immediately raised in the REPL session. The function return value is
then determined by the way the <em>REPL session</em> terminates: <code class="docutils literal notranslate"><span class="pre">0</span></code>, <code class="docutils literal notranslate"><span class="pre">1</span></code>, or
the status of a <a class="reference internal" href="../library/exceptions.html#SystemExit" title="SystemExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code></a>, as specified above.</p>
<p>This function always finalizes the Python interpreter before it returns.</p>
<p>See <a class="reference internal" href="init_config.html#init-python-config"><span class="std std-ref">Python Configuration</span></a> for an example of a
customized Python that always runs in isolated mode using
<a class="reference internal" href="#c.Py_RunMain" title="Py_RunMain"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_RunMain()</span></code></a>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyUnstable_AtExit">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyUnstable_AtExit</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="subinterpreters.html#c.PyInterpreterState" title="PyInterpreterState"><span class="n"><span class="pre">PyInterpreterState</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">interp</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">(</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">func</span></span><span class="p"><span class="pre">)</span></span><span class="p"><span class="pre">(</span></span><span class="kt"><span class="pre">void</span></span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">)</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">data</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnstable_AtExit" title="Link to this definition">¶</a><br /></dt>
<dd><div class="unstable-c-api warning admonition">
<em>This is <a class="reference internal" href="stable.html#unstable-c-api"><span class="std std-ref">Unstable API</span></a>. It may change without warning in minor releases.</em></div>
<p>Register an <a class="reference internal" href="../library/atexit.html#module-atexit" title="atexit: Register and execute cleanup functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">atexit</span></code></a> callback for the target interpreter <em>interp</em>.
This is similar to <a class="reference internal" href="sys.html#c.Py_AtExit" title="Py_AtExit"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_AtExit()</span></code></a>, but takes an explicit interpreter and
data pointer for the callback.</p>
<p>There must be an <a class="reference internal" href="../glossary.html#term-attached-thread-state"><span class="xref std std-term">attached thread state</span></a> for <em>interp</em>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.13.</span></p>
</div>
</dd></dl>
</section>
<section id="cautions-regarding-interpreter-finalization">
<span id="cautions-regarding-runtime-finalization"></span><h2>Cautions regarding interpreter finalization<a class="headerlink" href="#cautions-regarding-interpreter-finalization" title="Link to this heading">¶</a></h2>
<p>In the late stage of <a class="reference internal" href="../glossary.html#term-interpreter-shutdown"><span class="xref std std-term">interpreter shutdown</span></a>, after attempting to wait for
non-daemon threads to exit (though this can be interrupted by
<a class="reference internal" href="../library/exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-class docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a>) and running the <a class="reference internal" href="../library/atexit.html#module-atexit" title="atexit: Register and execute cleanup functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">atexit</span></code></a> functions, the runtime
is marked as finalizing, meaning that <a class="reference internal" href="#c.Py_IsFinalizing" title="Py_IsFinalizing"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_IsFinalizing()</span></code></a> and
<a class="reference internal" href="../library/sys.html#sys.is_finalizing" title="sys.is_finalizing"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.is_finalizing()</span></code></a> return true. At this point, only the finalization
thread (the thread that initiated finalization; this is typically the main thread)
is allowed to <a class="reference internal" href="../glossary.html#term-attached-thread-state"><span class="xref std std-term">attach</span></a> a thread state.</p>
<p>Other threads that attempt to attach during finalization, either explicitly
(such as via <a class="reference internal" href="threads.html#c.PyThreadState_Ensure" title="PyThreadState_Ensure"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyThreadState_Ensure()</span></code></a> or <a class="reference internal" href="threads.html#c.Py_END_ALLOW_THREADS" title="Py_END_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_END_ALLOW_THREADS</span></code></a>)
or implicitly (such as in-between bytecode instructions), will enter a
<strong>permanently blocked state</strong>. Generally, this is harmless, but this can
result in deadlocks. For example, a thread may be permanently blocked while
holding a lock, meaning that the finalization thread can never acquire that
lock.</p>
<p>Prior to CPython 3.13, the thread would exit instead of hanging,
which led to other issues (see the warning note at
<a class="reference internal" href="threads.html#c.PyThread_exit_thread" title="PyThread_exit_thread"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyThread_exit_thread()</span></code></a>).</p>
<p>Gross? Yes. Starting in Python 3.15, there are a number of C APIs that make
it possible to avoid these issues by temporarily preventing finalization:</p>
<div class="admonition seealso" id="interpreter-guards">
<p class="admonition-title">See also</p>
<p><span class="target" id="index-16"></span><a class="pep reference external" href="https://peps.python.org/pep-0788/"><strong>PEP 788</strong></a> explains the design, motivation and rationale
for these APIs.</p>
</div>
<dl class="c type">
<dt class="sig sig-object c" id="c.PyInterpreterGuard">
<span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyInterpreterGuard</span></span></span><a class="headerlink" href="#c.PyInterpreterGuard" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> (as an opaque struct) since version 3.15.</em><p>An opaque interpreter guard structure.</p>
<p>By holding an interpreter guard, the caller can ensure that the interpreter
will not finalize until the guard is closed (through
<a class="reference internal" href="#c.PyInterpreterGuard_Close" title="PyInterpreterGuard_Close"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyInterpreterGuard_Close()</span></code></a>).</p>
<p>When a guard is held, a thread attempting to finalize the interpreter will
block until the guard is closed before starting finalization.
After finalization has started, threads are forever unable to acquire
guards for that interpreter. This means that if you forget to close an
interpreter guard, the process will <strong>permanently hang</strong> during
finalization!</p>
<p>Holding a guard for an interpreter is similar to holding a
<a class="reference internal" href="../glossary.html#term-strong-reference"><span class="xref std std-term">strong reference</span></a> to a Python object, except finalization does not happen
automatically after all guards are released: it requires an explicit
<a class="reference internal" href="subinterpreters.html#c.Py_EndInterpreter" title="Py_EndInterpreter"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_EndInterpreter()</span></code></a> call.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyInterpreterGuard_FromCurrent">
<a class="reference internal" href="#c.PyInterpreterGuard" title="PyInterpreterGuard"><span class="n"><span class="pre">PyInterpreterGuard</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyInterpreterGuard_FromCurrent</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterGuard_FromCurrent" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Create a finalization guard for the current interpreter. This will prevent
finalization until the guard is closed.</p>
<p>For example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// Temporarily prevent finalization.</span>
<span class="n">PyInterpreterGuard</span><span class="w"> </span><span class="o">*</span><span class="n">guard</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">PyInterpreterGuard_FromCurrent</span><span class="p">();</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">guard</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="nb">NULL</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="c1">// Finalization has already started or we're out of memory.</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="nb">NULL</span><span class="p">;</span>
<span class="p">}</span>
<span class="n">Py_BEGIN_ALLOW_THREADS</span><span class="p">;</span>
<span class="c1">// Do some critical processing here. For example, we can safely acquire</span>
<span class="c1">// locks that might be acquired by the finalization thread.</span>
<span class="n">Py_END_ALLOW_THREADS</span><span class="p">;</span>
<span class="c1">// Now that we're done with our critical processing, the interpreter is</span>
<span class="c1">// allowed to finalize again.</span>
<span class="n">PyInterpreterGuard_Close</span><span class="p">(</span><span class="n">guard</span><span class="p">);</span>
</pre></div>
</div>
<p>On success, this function returns a guard for the current interpreter;
on failure, it returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code> with an exception set.</p>
<p>This function will fail only if the current interpreter has already started
finalizing, or if the process is out of memory.</p>
<p>The guard pointer returned by this function must be eventually closed
with <a class="reference internal" href="#c.PyInterpreterGuard_Close" title="PyInterpreterGuard_Close"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyInterpreterGuard_Close()</span></code></a>; failing to do so will result in
the Python process infinitely hanging.</p>
<p>The caller must hold an <a class="reference internal" href="../glossary.html#term-attached-thread-state"><span class="xref std std-term">attached thread state</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyInterpreterGuard_FromView">
<a class="reference internal" href="#c.PyInterpreterGuard" title="PyInterpreterGuard"><span class="n"><span class="pre">PyInterpreterGuard</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyInterpreterGuard_FromView</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyInterpreterView" title="PyInterpreterView"><span class="n"><span class="pre">PyInterpreterView</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">view</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterGuard_FromView" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Create a finalization guard for an interpreter through a view.</p>
<p>On success, this function returns a guard to the interpreter
represented by <em>view</em>. The view is still valid after calling this
function. The guard must eventually be closed with
<a class="reference internal" href="#c.PyInterpreterGuard_Close" title="PyInterpreterGuard_Close"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyInterpreterGuard_Close()</span></code></a>.</p>
<p>If the interpreter no longer exists, is already finalizing, or out of memory,
then this function returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code> without setting an exception.</p>
<p>The caller does not need to hold an <a class="reference internal" href="../glossary.html#term-attached-thread-state"><span class="xref std std-term">attached thread state</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyInterpreterGuard_Close">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyInterpreterGuard_Close</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyInterpreterGuard" title="PyInterpreterGuard"><span class="n"><span class="pre">PyInterpreterGuard</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">guard</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterGuard_Close" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Close an interpreter guard, allowing the interpreter to start
finalization if no other guards remain. If an interpreter guard
is never closed, the interpreter will infinitely wait when trying
to enter finalization!</p>
<p>After an interpreter guard is closed, it may not be used in
<a class="reference internal" href="threads.html#c.PyThreadState_Ensure" title="PyThreadState_Ensure"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyThreadState_Ensure()</span></code></a>. Doing so will result in undefined
behavior.</p>
<p>This function cannot fail, and the caller doesn’t need to hold an
<a class="reference internal" href="../glossary.html#term-attached-thread-state"><span class="xref std std-term">attached thread state</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
</section>
<section id="interpreter-views">
<span id="id1"></span><h2>Interpreter views<a class="headerlink" href="#interpreter-views" title="Link to this heading">¶</a></h2>
<p>In some cases, it may be necessary to access an interpreter that may have been
deleted. This can be done using interpreter views.</p>
<dl class="c type">
<dt class="sig sig-object c" id="c.PyInterpreterView">
<span class="k"><span class="pre">type</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyInterpreterView</span></span></span><a class="headerlink" href="#c.PyInterpreterView" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> (as an opaque struct) since version 3.15.</em><p>An opaque view of an interpreter.</p>
<p>This is a thread-safe way to access an interpreter that may have be
finalizing or already destroyed.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyInterpreterView_FromCurrent">
<a class="reference internal" href="#c.PyInterpreterView" title="PyInterpreterView"><span class="n"><span class="pre">PyInterpreterView</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyInterpreterView_FromCurrent</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterView_FromCurrent" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Create a view to the current interpreter.</p>
<p>This function is generally meant to be used alongside
<a class="reference internal" href="#c.PyInterpreterGuard_FromView" title="PyInterpreterGuard_FromView"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyInterpreterGuard_FromView()</span></code></a> or <a class="reference internal" href="threads.html#c.PyThreadState_EnsureFromView" title="PyThreadState_EnsureFromView"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyThreadState_EnsureFromView()</span></code></a>.</p>
<p>On success, this function returns a view to the current interpreter; on
failure, it returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code> with an exception set.</p>
<p>The caller must hold an <a class="reference internal" href="../glossary.html#term-attached-thread-state"><span class="xref std std-term">attached thread state</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyInterpreterView_Close">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PyInterpreterView_Close</span></span></span><span class="sig-paren">(</span><a class="reference internal" href="#c.PyInterpreterView" title="PyInterpreterView"><span class="n"><span class="pre">PyInterpreterView</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">view</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterView_Close" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Close an interpreter view.</p>
<p>If an interpreter view is never closed, the view’s memory will never be
freed, but there are no other consequences. (In contrast, forgetting to
close a guard will infinitely hang the main thread during finalization.)</p>
<p>This function cannot fail, and the caller doesn’t need to hold an
<a class="reference internal" href="../glossary.html#term-attached-thread-state"><span class="xref std std-term">attached thread state</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PyInterpreterView_FromMain">
<a class="reference internal" href="#c.PyInterpreterView" title="PyInterpreterView"><span class="n"><span class="pre">PyInterpreterView</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">PyInterpreterView_FromMain</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterView_FromMain" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.15.</em><p>Create a view for the main interpreter (the first and default
interpreter in a Python process; see
<a class="reference internal" href="subinterpreters.html#c.PyInterpreterState_Main" title="PyInterpreterState_Main"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyInterpreterState_Main()</span></code></a>).</p>
<p>On success, this function returns a view to the main
interpreter; on failure, it returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code> without an exception set.
Failure indicates that the process is out of memory.</p>
<p>Use this function when an interpreter pointer or view cannot be supplied
by the caller, such as when a native threading library does not provide a
<code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*arg</span></code> parameter that could carry a <a class="reference internal" href="#c.PyInterpreterGuard" title="PyInterpreterGuard"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyInterpreterGuard</span></code></a> or
<a class="reference internal" href="#c.PyInterpreterView" title="PyInterpreterView"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyInterpreterView</span></code></a>. In code that supports subinterpreters, prefer
<a class="reference internal" href="#c.PyInterpreterView_FromCurrent" title="PyInterpreterView_FromCurrent"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyInterpreterView_FromCurrent()</span></code></a> so the guard tracks the calling
interpreter rather than the main one.</p>
<p>The caller does not need to hold an <a class="reference internal" href="../glossary.html#term-attached-thread-state"><span class="xref std std-term">attached thread state</span></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.15.</span></p>
</div>
</dd></dl>
</section>
<section id="process-wide-parameters">
<h2>Process-wide parameters<a class="headerlink" href="#process-wide-parameters" title="Link to this heading">¶</a></h2>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_SetProgramName">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_SetProgramName</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">wchar_t</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">name</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_SetProgramName" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-17">This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.program_name" title="PyConfig.program_name"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.program_name</span></code></a> should be used instead, see <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python
Initialization Configuration</span></a>.</p>
<p>This function should be called before <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> is called for
the first time, if it is called at all. It tells the interpreter the value
of the <code class="docutils literal notranslate"><span class="pre">argv[0]</span></code> argument to the <code class="xref c c-func docutils literal notranslate"><span class="pre">main()</span></code> function of the program
(converted to wide characters).
This is used by some other functions below to find
the Python run-time libraries relative to the interpreter executable. The
default value is <code class="docutils literal notranslate"><span class="pre">'python'</span></code>. The argument should point to a
zero-terminated wide character string in static storage whose contents will not
change for the duration of the program’s execution. No code in the Python
interpreter will change the contents of this storage.</p>
<p>Use <a class="reference internal" href="sys.html#c.Py_DecodeLocale" title="Py_DecodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DecodeLocale()</span></code></a> to decode a bytes string to get a
<span class="c-expr sig sig-inline c"><span class="n">wchar_t</span><span class="p">*</span></span> string.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.11, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_GetVersion">
<span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">Py_GetVersion</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetVersion" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the version of this Python interpreter. This is a string that looks
something like</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="s">"3.0a5+ (py3k:63103M, May 12 2008, 00:53:55) </span><span class="se">\n</span><span class="s">[GCC 4.2.3]"</span>
</pre></div>
</div>
<p id="index-18">The first word (up to the first space character) is the current Python version;
the first characters are the major and minor version separated by a
period. The returned string points into static storage; the caller should not
modify its value. The value is available to Python code as <a class="reference internal" href="../library/sys.html#sys.version" title="sys.version"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.version</span></code></a>.</p>
<p>See also the <a class="reference internal" href="apiabiversion.html#c.Py_Version" title="Py_Version"><code class="xref c c-var docutils literal notranslate"><span class="pre">Py_Version</span></code></a> constant.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_GetPlatform">
<span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">Py_GetPlatform</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetPlatform" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-19">Return the platform identifier for the current platform. On Unix, this is
formed from the “official” name of the operating system, converted to lower
case, followed by the major revision number; e.g., for Solaris 2.x, which is
also known as SunOS 5.x, the value is <code class="docutils literal notranslate"><span class="pre">'sunos5'</span></code>. On macOS, it is
<code class="docutils literal notranslate"><span class="pre">'darwin'</span></code>. On Windows, it is <code class="docutils literal notranslate"><span class="pre">'win'</span></code>. The returned string points into
static storage; the caller should not modify its value. The value is available
to Python code as <code class="docutils literal notranslate"><span class="pre">sys.platform</span></code>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_GetCopyright">
<span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">Py_GetCopyright</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetCopyright" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the official copyright string for the current Python version, for example</p>
<p><code class="docutils literal notranslate"><span class="pre">'Copyright</span> <span class="pre">1991-1995</span> <span class="pre">Stichting</span> <span class="pre">Mathematisch</span> <span class="pre">Centrum,</span> <span class="pre">Amsterdam'</span></code></p>
<p id="index-20">The returned string points into static storage; the caller should not modify its
value. The value is available to Python code as <code class="docutils literal notranslate"><span class="pre">sys.copyright</span></code>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_GetCompiler">
<span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">Py_GetCompiler</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetCompiler" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return an indication of the compiler used to build the current Python version,
in square brackets, for example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="s">"[GCC 2.7.2.2]"</span>
</pre></div>
</div>
<p id="index-21">The returned string points into static storage; the caller should not modify its
value. The value is available to Python code as part of the variable
<code class="docutils literal notranslate"><span class="pre">sys.version</span></code>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_GetBuildInfo">
<span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="kt"><span class="pre">char</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">Py_GetBuildInfo</span></span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetBuildInfo" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return information about the sequence number and build date and time of the
current Python interpreter instance, for example</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="s">"#67, Aug 1 1997, 22:34:28"</span>
</pre></div>
</div>
<p id="index-22">The returned string points into static storage; the caller should not modify its
value. The value is available to Python code as part of the variable
<code class="docutils literal notranslate"><span class="pre">sys.version</span></code>.</p>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PySys_SetArgvEx">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PySys_SetArgvEx</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">argc</span></span>, <span class="n"><span class="pre">wchar_t</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">argv</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">updatepath</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_SetArgvEx" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-23">This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.argv" title="PyConfig.argv"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.argv</span></code></a>, <a class="reference internal" href="init_config.html#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.parse_argv</span></code></a> and
<a class="reference internal" href="init_config.html#c.PyConfig.safe_path" title="PyConfig.safe_path"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.safe_path</span></code></a> should be used instead, see <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python
Initialization Configuration</span></a>.</p>
<p>Set <a class="reference internal" href="../library/sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.argv</span></code></a> based on <em>argc</em> and <em>argv</em>. These parameters are
similar to those passed to the program’s <code class="xref c c-func docutils literal notranslate"><span class="pre">main()</span></code> function with the
difference that the first entry should refer to the script file to be
executed rather than the executable hosting the Python interpreter. If there
isn’t a script that will be run, the first entry in <em>argv</em> can be an empty
string. If this function fails to initialize <code class="xref py py-data docutils literal notranslate"><span class="pre">sys.argv</span></code>, a fatal
condition is signalled using <a class="reference internal" href="sys.html#c.Py_FatalError" title="Py_FatalError"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_FatalError()</span></code></a>.</p>
<p>If <em>updatepath</em> is zero, this is all the function does. If <em>updatepath</em>
is non-zero, the function also modifies <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> according to the
following algorithm:</p>
<ul class="simple">
<li><p>If the name of an existing script is passed in <code class="docutils literal notranslate"><span class="pre">argv[0]</span></code>, the absolute
path of the directory where the script is located is prepended to
<a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>.</p></li>
<li><p>Otherwise (that is, if <em>argc</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code> or <code class="docutils literal notranslate"><span class="pre">argv[0]</span></code> doesn’t point
to an existing file name), an empty string is prepended to
<a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>, which is the same as prepending the current working
directory (<code class="docutils literal notranslate"><span class="pre">"."</span></code>).</p></li>
</ul>
<p>Use <a class="reference internal" href="sys.html#c.Py_DecodeLocale" title="Py_DecodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DecodeLocale()</span></code></a> to decode a bytes string to get a
<span class="c-expr sig sig-inline c"><span class="n">wchar_t</span><span class="p">*</span></span> string.</p>
<p>See also <a class="reference internal" href="init_config.html#c.PyConfig.orig_argv" title="PyConfig.orig_argv"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.orig_argv</span></code></a> and <a class="reference internal" href="init_config.html#c.PyConfig.argv" title="PyConfig.argv"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.argv</span></code></a>
members of the <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>It is recommended that applications embedding the Python interpreter
for purposes other than executing a single script pass <code class="docutils literal notranslate"><span class="pre">0</span></code> as <em>updatepath</em>,
and update <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> themselves if desired.
See <span class="target" id="index-24"></span><a class="cve reference external" href="https://www.cve.org/CVERecord?id=CVE-2008-5983"><strong>CVE 2008-5983</strong></a>.</p>
<p>On versions before 3.1.3, you can achieve the same effect by manually
popping the first <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> element after having called
<a class="reference internal" href="#c.PySys_SetArgv" title="PySys_SetArgv"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySys_SetArgv()</span></code></a>, for example using:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyRun_SimpleString</span><span class="p">(</span><span class="s">"import sys; sys.path.pop(0)</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 3.1.3.</span></p>
</div>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.11, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.PySys_SetArgv">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">PySys_SetArgv</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">argc</span></span>, <span class="n"><span class="pre">wchar_t</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">argv</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_SetArgv" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.argv" title="PyConfig.argv"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.argv</span></code></a> and <a class="reference internal" href="init_config.html#c.PyConfig.parse_argv" title="PyConfig.parse_argv"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.parse_argv</span></code></a> should be used
instead, see <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<p>This function works like <a class="reference internal" href="#c.PySys_SetArgvEx" title="PySys_SetArgvEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySys_SetArgvEx()</span></code></a> with <em>updatepath</em> set
to <code class="docutils literal notranslate"><span class="pre">1</span></code> unless the <strong class="program">python</strong> interpreter was started with the
<a class="reference internal" href="../using/cmdline.html#cmdoption-I"><code class="xref std std-option docutils literal notranslate"><span class="pre">-I</span></code></a>.</p>
<p>Use <a class="reference internal" href="sys.html#c.Py_DecodeLocale" title="Py_DecodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DecodeLocale()</span></code></a> to decode a bytes string to get a
<span class="c-expr sig sig-inline c"><span class="n">wchar_t</span><span class="p">*</span></span> string.</p>
<p>See also <a class="reference internal" href="init_config.html#c.PyConfig.orig_argv" title="PyConfig.orig_argv"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.orig_argv</span></code></a> and <a class="reference internal" href="init_config.html#c.PyConfig.argv" title="PyConfig.argv"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.argv</span></code></a>
members of the <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python Initialization Configuration</span></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.4: </span>The <em>updatepath</em> value depends on <a class="reference internal" href="../using/cmdline.html#cmdoption-I"><code class="xref std std-option docutils literal notranslate"><span class="pre">-I</span></code></a>.</p>
</div>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.11, removed in version 3.15.</span></p>
</div>
</dd></dl>
<dl class="c function">
<dt class="sig sig-object c" id="c.Py_SetPythonHome">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">Py_SetPythonHome</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">const</span></span><span class="w"> </span><span class="n"><span class="pre">wchar_t</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">home</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_SetPythonHome" title="Link to this definition">¶</a><br /></dt>
<dd><em class="stableabi"> Part of the <a class="reference internal" href="stable.html#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This API is kept for backward compatibility: setting
<a class="reference internal" href="init_config.html#c.PyConfig.home" title="PyConfig.home"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyConfig.home</span></code></a> should be used instead, see <a class="reference internal" href="init_config.html#init-config"><span class="std std-ref">Python
Initialization Configuration</span></a>.</p>
<p>Set the default “home” directory, that is, the location of the standard
Python libraries. See <span class="target" id="index-25"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a> for the meaning of the
argument string.</p>
<p>The argument should point to a zero-terminated character string in static
storage whose contents will not change for the duration of the program’s
execution. No code in the Python interpreter will change the contents of
this storage.</p>
<p>Use <a class="reference internal" href="sys.html#c.Py_DecodeLocale" title="Py_DecodeLocale"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DecodeLocale()</span></code></a> to decode a bytes string to get a
<span class="c-expr sig sig-inline c"><span class="n">wchar_t</span><span class="p">*</span></span> string.</p>
<div class="deprecated-removed">
<p><span class="versionmodified removed">Deprecated since version 3.11, removed in version 3.15.</span></p>
</div>
</dd></dl>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Interpreter initialization and finalization</a><ul>
<li><a class="reference internal" href="#before-python-initialization">Before Python initialization</a></li>
<li><a class="reference internal" href="#global-configuration-variables">Global configuration variables</a></li>
<li><a class="reference internal" href="#initializing-and-finalizing-the-interpreter">Initializing and finalizing the interpreter</a></li>
<li><a class="reference internal" href="#cautions-regarding-interpreter-finalization">Cautions regarding interpreter finalization</a></li>
<li><a class="reference internal" href="#interpreter-views">Interpreter views</a></li>
<li><a class="reference internal" href="#process-wide-parameters">Process-wide parameters</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="datetime.html"
title="previous chapter">DateTime Objects</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="threads.html"
title="next chapter">Thread states and the global interpreter lock</a></p>
</div>
<script>
document.addEventListener('DOMContentLoaded', () => {
const title = document.querySelector('meta[property="og:title"]').content;
const elements = document.querySelectorAll('.improvepage');
const pageurl = window.location.href.split('?')[0];
elements.forEach(element => {
const url = new URL(element.href.split('?')[0].replace("-nojs", ""));
url.searchParams.set('pagetitle', title);
url.searchParams.set('pageurl', pageurl);
url.searchParams.set('pagesource', "c-api/interp-lifecycle.rst");
element.href = url.toString();
});
});
</script>
<div role="note" aria-label="source link">
<h3>This page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a bug</a></li>
<li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>
<li>
<a href="https://github.com/python/cpython/blob/main/Doc/c-api/interp-lifecycle.rst?plain=1"
rel="nofollow">Show source
</a>
</li>
</ul>
</div>
</div>
<div id="sidebarbutton" title="Collapse sidebar">
<span>«</span>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="threads.html" title="Thread states and the global interpreter lock"
>next</a> |</li>
<li class="right" >
<a href="datetime.html" title="DateTime Objects"
>previous</a> |</li>
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li class="switchers">
<div class="language_switcher_placeholder"></div>
<div class="version_switcher_placeholder"></div>
</li>
<li>
</li>
<li id="cpython-language-and-version">
<a href="../index.html">3.15.0rc1 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API reference manual</a> »</li>
<li class="nav-item nav-item-this"><a href="">Interpreter initialization and finalization</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">
<input type="submit" value="Go">
</form>
</div>
|
</li>
<li class="right">
<label class="theme-selector-label">
Theme
<select class="theme-selector" oninput="activateTheme(this.value)">
<option value="auto" selected>Auto</option>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</label> |</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.
<br>
This page is licensed under the Python Software Foundation License Version 2.
<br>
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
<br>
See <a href="/license.html">History and License</a> for more information.<br>
<br>
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br>
<br>
Last updated on Aug 04, 2026 (11:13 UTC).
<a href="/bugs.html">Found a bug</a>?
<br>
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>